<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>DonReY Framework :: DRY Template Transform</title>
<link rel='stylesheet' type='text/css' href='/Documentation/DonReY.css' media='screen' />
</head>
<body>
<a href="/documentation/donrey.html" title="DonReY Framework Documentation">DonReY Framework Documentation</a> &raquo; <a href="/documentation/structure.html" title="Framework structure">Framework structure</a> &raquo; <a href="/documentation/structure/modules.html" title="Modules">Modules</a> &raquo; <a href="/documentation/structure/modules/render.html" title="Render Module">Render Module</a> &raquo; DRY Template Transform
<hr />
	<h2>Render Module &raquo; <span class="caps">DRY</span> Template Transform</h2>

	<p>This is DonReY&#8217;s own templating system. It uses a minimalist syntax for representing logic blocks inside the template.</p>

	<p>At it&#8217;s most basic level, it&#8217;s a variable search-and-replace mechanism. It doesn&#8217;t attempt to simulate a programming language, instead it focuses on being minimally intrusive in your template. For example, if you need a section of the template to be displayed if a variable exists (of it it doesn&#8217;t exist) and is not empty, you write this:</p>

<pre><code>{#if:logged_in:Hello {user}, welcome}{#ifnot:logged_in:You are not logged in} 
</code></pre>

	<p>In this example, the <span class="caps">DRY</span> Template mark-up is surrounded by <em>curly brackets { }</em>. Everything inside them is analysed and processed, everything outside is displayed as-is.</p>

	<p><em>First pair of curly brackets contains:</em> <br />
<strong>#if</strong> &#8211; A keyword indicating to check a variable<br />
<strong>logged_in</strong> &#8211; Name of that variable<br />
<strong>Hello {user}, welcome</strong> &#8211; what to be analysed and displayed if <em>logged_in</em> exists and is not null, empty or false</p>

	<p>Note that there&#8217;s another bracket pair {user} , which is detected and analysed. Without any special keyword, the content of this bracket will simply display what the variable <strong>user</strong> contains.</p>

	<p>Second pair is identical, however it will be analysed and shown only if the variable doesn&#8217;t exist, or if it&#8217;s null, empty or false</p>

	<h3>Principle of operation</h3>

	<p>[ here comes the programming part on how to load this Transform and how to use it ]</p>

	<h3>Template Syntax</h3>

	<p><span class="caps">DRY</span> Template receives structured data as a parameter, a <span class="caps">PHP</span> array or object. That data can be searched for keys or members, and it has a <em>root</em>, which represents the data itself (the incoming array or object).  </p>

	<ul>
		<li><a href="#comments">!Comments</a></li>
		<li><a href="#escape">@Escaping</a></li>
		<li><a href="#data">{Data placeholders}</a>
	<ul>
		<li><a href="#simpledata">Basic variable search</a></li>
		<li><a href="#deepdata">Deep variable search</a></li>
		<li><a href="#dynamicname">Dynamic variable names</a></li>
		<li><a href="#selfdata">$Self</a></li>
		<li><a href="#rootdata">^Root access</a></li>
	</ul></li>
		<li><a href="#keywords">Keywords</a>
	<ul>
		<li><a href="#kwuse">#USE</a></li>
		<li><a href="#kwroot">#ROOT</a></li>
		<li><a href="#kwif">#IF</a></li>
		<li><a href="#kwifnot">#IFNOT</a></li>
		<li><a href="#kwrepeat">#REPEAT</a>
	<ul>
		<li><a href="#kwbreak">#BREAK</a></li>
	</ul></li>
		<li>#STORE</li>
		<li>#INCLUDE</li>
		<li>#LOAD</li>
	</ul></li>
		<li>~Output Modifiers~
	<ul>
		<li><span class="caps">PHP</span> string function wrappers (uppercase, capitalize, reverse, etc.)</li>
		<li>htmlstripspaces</li>
		<li>wordwrap</li>
		<li>cut</li>
	</ul></li>
	</ul>

	<h4 id="comments">Comments</h4>

	<p>Comments are sections of the template which will not appear in the rendered version. To place a comment use exclamation <strong>!</strong> sign:</p>

<pre><code>{!This text will not appear}
</code></pre>

	<h4 id="escape">Escaping</h4>

	<p>If you want the parsed to ignore some text or mark-up in your template, use the &#8220;at&#8221; <strong>@</strong> sign:</p>

<pre><code>{@I can put {curly braces} or {#anything:else} and they will be displayed as-is}
</code></pre>

	<h4 id="data">Data placeholders</h4>

	<p><span class="caps">DRY</span> Template&#8217;s primary function is to replace placeholders with variables found in the input object. There are several variants of searching for that data, but generally it&#8217;s a quick and simple syntax.</p>

	<p id="simpledata"><em>Basic variable search</em> &#8211; Displaying content of <em>$data[&#8216;myVariable&#8217;]</em> or <em>$data-&gt; myVariable</em>:</p>

<pre><code>{myVariable}
</code></pre>

	<p id="deepdata"><em>Deep variable search</em> &#8211; Displaying content of <em>$data[&#8216;foo&#8217;][&#8216;bar&#8217;]</em> or <em>$data-&gt; foo-&gt; bar</em>:</p>

	<p>The parser supports any depth, so organize your data the way you see fit. A combination of arrays and objects is supported, so <em>$data[&#8216;foo&#8217;]-&gt; bar</em> works.</p>

<pre><code>{foo.bar}
</code></pre>

	<p id="dynamicname">It is possible to construct a <em>dynamic variable name</em>, from the content of other variables.</p>

	<p>In this case, if <em>bar</em>&#8217;s value is &#8220;one&#8221; the searched variable will be <em>$data[&#8216;foo_one&#8217;]</em>:</p>

<pre><code>{foo_{bar}}
</code></pre>

	<p>Actually, <strong>anything</strong> can be inside a variable name, for example, a text assambled from multiple other variables.</p>

	<p>If <em>year</em>&#8217;s value is &#8220;2012&#8221;, <em>month</em>&#8217;s value is &#8220;February&#8221; and <em>day</em>&#8217;s value is &#8220;29&#8221;, the template system will search for <em>$data[&#8216;Date_2012_February_29&#8217;]</em>:</p>

<pre><code>{Date_{year}_{month}_{day}}
</code></pre>

	<p id="selfdata">Sometimes it&#8217;s necessary to access the <em>data itself</em>, and not search for a member. In such cases, use the dollar <strong>$</strong> sign.</p>

	<p>Supposedly the passed data is an object that has defined the <strong>__toString()</strong> method, this syntax will attempt to convert the object to a string. However, it has better uses inside other placeholders, like the <a href="#kwuse">#USE</a> or <a href="#kwrepeat">#REPEAT</a> keywords:</p>

<pre><code>{$}
</code></pre>

	<p id="rootdata">Please read the Keywords section &#8211; <a href="#kwuse">#USE</a> keyword to understand the <em>scope</em> of data search and what the root sign does:</p>

<pre><code>{^rootvar}
</code></pre>

	<h4 id="keywords">Special Keywords</h4>

	<p>While it would be possible to use various other signs or sign combinations for extended functionality, keywords allow a more clear syntax in case of complex placeholders. Usually, where a keyword appears there&#8217;s a combination of variables and sub-content, sepparated by double-colon <strong>:</strong> sign.</p>

	<h4 id="kwuse">#USE keyword</h4>

	<p>This keyword allows shorter variable identifiers inside the placeholder. Supposedly the data is an array that looks like this:</p>

<pre class="php"><span class="sy0"></span><span class="re0">$data</span> <span class="sy0">=</span> <span class="kw3">array</span><span class="br0">&#40;</span>
	<span class="st_h">'greek'</span><span class="sy0">=&gt;</span> <span class="kw3">array</span><span class="br0">&#40;</span><span class="st_h">'a'</span><span class="sy0">=&gt;</span><span class="st_h">'Alpha'</span><span class="sy0">,</span> <span class="st_h">'b'</span><span class="sy0">=&gt;</span><span class="st_h">'Beta'</span><span class="sy0">,</span> <span class="st_h">'c'</span><span class="sy0">=&gt;</span><span class="st_h">'Gamma'</span><span class="sy0">,</span> <span class="st_h">'d'</span><span class="sy0">=&gt;</span><span class="st_h">'Delta'</span><span class="br0">&#41;</span><span class="sy0">,</span>
	<span class="st_h">'roman'</span><span class="sy0">=&gt;</span> <span class="kw3">array</span><span class="br0">&#40;</span><span class="st_h">'a'</span><span class="sy0">=&gt;</span> <span class="st0">&quot;I&quot;</span><span class="sy0">,</span> <span class="st_h">'b'</span><span class="sy0">=&gt;</span> <span class="st0">&quot;II&quot;</span><span class="sy0">,</span> <span class="st_h">'c'</span><span class="sy0">=&gt;</span> <span class="st0">&quot;III&quot;</span><span class="br0">&#41;</span><span class="sy0">,</span>
	<span class="st_h">'foo'</span><span class="sy0">=&gt;</span> <span class="st0">&quot;Bar&quot;</span>
<span class="br0">&#41;</span><span class="sy0">;</span></pre>

	<p>to access all four greek letters <em>$data[&#8216;greek&#8217;][&#8216;a&#8217;], $data[&#8216;greek&#8217;][&#8216;b&#8217;], $data[&#8216;greek&#8217;][&#8216;c&#8217;] and $data[&#8216;greek&#8217;][&#8216;d&#8217;]</em> you could write</p>

<pre><code>Greek letters: {greek.a}, {greek.b}, {greek.c}, {greek.d}
</code></pre>

	<p>or use the #USE keyword, to make the syntax shorter and more efficient (this is very useful when using long key names in your arrays or objects):</p>

<pre><code>Greek letters: {#USE:greek:{a} {b} {c} {d}}
</code></pre>

	<p>Inside the #USE keyword, the <em>scope</em> of variables have changed from <strong>root</strong> to the mentioned variable (in our case, <strong>greek</strong>). In order to display one of the roman numerals inside it, we need a special syntax, which has two modes: Variable mode, using the caret <strong>^</strong> sign, and Keyword mode, using the <strong>#ROOT</strong> keyword:</p>

<pre><code>Greek letters: {#USE:greek:{a} {b} {c}, and two roman numbers: {^roman.a}, {^roman.b} (We&#39;re still inside #USE)}
  or the keyword variant:
Greek letters: {#USE:greek:{a} {b} {c}, and two roman numbers: {#ROOT:{roman.a} {roman.b}} (We&#39;re still inside #USE)}
</code></pre>

	<p>These example should display: <em>Greek Letters: Alpha Beta Gamma, and two roman numbers: I II (We&#8217;re still inside #USE)</em></p>

	<h4 id="kwroot">#ROOT keyword</h4>

	<p>Root access (keyword and variable) is actually more useful inside the #REPEAT keyword, to allow displaying content which is not part of the looped container.</p>

<pre><code>{#REPEAT:greek:{$} is {^foo},}
</code></pre>

	<p>These example should display: <em>Alpha is Bar, Beta is Bar, Gamma is Bar, Delta is Bar,</em></p>

	<h4 id="kwif">#IF keyword</h4>

	<p>#IF is very simple, it processes the content if the variable exists and is not null or empty or false, and doesn&#8217;t display it if it is. In this example, <strong>Hello World !</strong> appears if <em>$data[&#8216;displayThis&#8217;]</em> is <strong>true</strong> or <strong>1</strong> or a non-empty string, array</p>

<pre><code>{#IF:displayThis:&lt;b&gt;Hello World !&lt;/b&gt;}
</code></pre>

	<p>Note that this is a simple template engine, not a programming language, so &#8220;expressions&#8221; are not supported inside the template. Use <span class="caps">PHP</span> to generate a <em>true</em> or <em>false</em> value for the variable being checked by #IF, before sending data to the template !</p>

	<h4 id="kwifnot">#IFNOT keyword</h4>

	<p>#IFNOT is the exact opposit of IF, it processes the content if the variable doesn&#8217;t exist or is null or empty or false.</p>

<pre><code>{#IFNOT:hideThis:&lt;b&gt;If hideThis is true, I won&#39;t appear&lt;/b&gt;}
</code></pre>

	<h4 id="kwrepeat">#REPEAT keyword</h4>

	<p>One of the most useful syntaxes is the #REPEAT one, which iterates inside a container variable ( array or object ), displaying the content for each iteration. Like the #USE keyword, it changes the <em>scope</em> of variables for any placeholders inside this keyword. Supposedly the data is a table array (typical database result):</p>

<pre class="php"><span class="sy0"></span><span class="re0">$data</span> <span class="sy0">=</span> <span class="kw3">array</span><span class="br0">&#40;</span>
	<span class="kw3">array</span><span class="br0">&#40;</span><span class="st_h">'name'</span><span class="sy0">=&gt;</span> <span class="st0">&quot;John&quot;</span><span class="sy0">,</span> <span class="st_h">'email'</span><span class="sy0">=&gt;</span> <span class="st0">&quot;johndoe@gmail.com&quot;</span><span class="sy0">,</span> <span class="st_h">'age'</span><span class="sy0">=&gt;</span> <span class="nu0">27</span><span class="br0">&#41;</span><span class="sy0">,</span>
	<span class="kw3">array</span><span class="br0">&#40;</span><span class="st_h">'name'</span><span class="sy0">=&gt;</span> <span class="st0">&quot;Maria&quot;</span><span class="sy0">,</span> <span class="st_h">'email'</span><span class="sy0">=&gt;</span> <span class="st0">&quot;maria@yahoo.com&quot;</span><span class="sy0">,</span> <span class="st_h">'age'</span><span class="sy0">=&gt;</span> <span class="nu0">18</span><span class="br0">&#41;</span><span class="sy0">,</span>
	<span class="kw3">array</span><span class="br0">&#40;</span><span class="st_h">'name'</span><span class="sy0">=&gt;</span> <span class="st0">&quot;Andrew&quot;</span><span class="sy0">,</span> <span class="st_h">'email'</span><span class="sy0">=&gt;</span> <span class="st0">&quot;andrew@live.com&quot;</span><span class="sy0">,</span> <span class="st_h">'age'</span><span class="sy0">=&gt;</span> <span class="nu0">34</span><span class="br0">&#41;</span>
<span class="br0">&#41;</span><span class="sy0">;</span></pre>

	<p>To display these people in an <span class="caps">HTML</span> table you only need to simply write this syntax:</p>

<pre><code>&lt;table&gt;
&lt;th&gt;Name&lt;/th&gt;&lt;th&gt;E-mail&lt;th&gt;&lt;th&gt;Age&lt;/th&gt; 
{#REPEAT::&lt;tr&gt;&lt;td&gt;{name}&lt;/td&gt;&lt;td&gt;{email}&lt;/td&gt;&lt;td&gt;{age}&lt;/td&gt;&lt;/tr&gt;
}
&lt;/table&gt;
</code></pre>

	<p>The resulting <span class="caps">HTML</span> would look like:</p>

<pre class="html5"><span class="sc2">&lt;<span class="kw2">table</span>&gt;</span>
<span class="sc2">&lt;<span class="kw2">th</span>&gt;</span>Name<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">th</span>&gt;&lt;<span class="kw2">th</span>&gt;</span>E-mail<span class="sc2">&lt;<span class="kw2">th</span>&gt;&lt;<span class="kw2">th</span>&gt;</span>Age<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">th</span>&gt;</span> 
<span class="sc2">&lt;<span class="kw2">tr</span>&gt;&lt;<span class="kw2">td</span>&gt;</span>John<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">td</span>&gt;&lt;<span class="kw2">td</span>&gt;</span>johndoe@gmail.com<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">td</span>&gt;&lt;<span class="kw2">td</span>&gt;</span>27<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">td</span>&gt;&lt;<span class="sy0">/</span><span class="kw2">tr</span>&gt;</span>
<span class="sc2">&lt;<span class="kw2">tr</span>&gt;&lt;<span class="kw2">td</span>&gt;</span>Maria<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">td</span>&gt;&lt;<span class="kw2">td</span>&gt;</span>maria@yahoo.com<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">td</span>&gt;&lt;<span class="kw2">td</span>&gt;</span>18<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">td</span>&gt;&lt;<span class="sy0">/</span><span class="kw2">tr</span>&gt;</span>
<span class="sc2">&lt;<span class="kw2">tr</span>&gt;&lt;<span class="kw2">td</span>&gt;</span>Andrew<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">td</span>&gt;&lt;<span class="kw2">td</span>&gt;</span>andrew@live.com<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">td</span>&gt;&lt;<span class="kw2">td</span>&gt;</span>34<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">td</span>&gt;&lt;<span class="sy0">/</span><span class="kw2">tr</span>&gt;</span>
<span class="sc2">&lt;<span class="sy0">/</span><span class="kw2">table</span>&gt;</span></pre>

	<p>And the table would look like:</p>

	<table>
		<tr>
			<td><strong>Name</strong></td>
			<td><strong>E-mail</strong></td>
			<td><strong>Age</strong></td>
		</tr>
		<tr>
			<td>John</td>
			<td>johndoe@gmail.com</td>
			<td>27</td>
		</tr>
		<tr>
			<td>Maria</td>
			<td>maria@yahoo.com</td>
			<td>18</td>
		</tr>
		<tr>
			<td>Andrew</td>
			<td>andrew@live.com</td>
			<td>34</td>
		</tr>
	</table>

	<h4 id="kwbreak">#BREAK keyword</h4>

	<p>#BREAK is used only inside a #REPEAT syntax, and when it&#8217;s variable evaluates to true (just like for <a href="#kwif">#IF</a>) it stops the iteration. Anything after the #BREAK keyword doesn&#8217;t appear anymore.</p>

	<p>In the next example, let&#8217;s say we have a variable named <strong>lastrow</strong> in the array, which appears only on one single row of the data. No rows after that one will be shown:</p>

<pre><code>&lt;table&gt;
&lt;th&gt;Name&lt;/th&gt;&lt;th&gt;E-mail&lt;th&gt;&lt;th&gt;Age&lt;/th&gt; 
{#REPEAT::&lt;tr&gt;&lt;td&gt;{name}&lt;/td&gt;&lt;td&gt;{email}&lt;/td&gt;&lt;td&gt;{age}&lt;/td&gt;&lt;/tr&gt;
{#BREAK:lastrow}}
&lt;/table&gt;
</code></pre>
</body>
</html>
<!-- http://www.donrey.net/Documentation - Built with DonReY Framework http://www.donrey.net/ - Powered by PHP, MySQL, JavaScript -->